External Binary Entities

We have already discussed how to include external XML documents (entities) in your primary XML document (entity).

. . . (omitted)
<!ENTITY entity.name SYSTEM|PUBLIC “URI”>
. . . (omitted)
&entity.name;
. . . (omitted)

This physically includes the content of the external entity into the document when it is processed.  We have also discussed referencing external entities within ENTITY attribute types, which does not include the content directly, but is still parsed.

. . . (omitted)
<!ENTITY entity.name SYSTEM|PUBLIC “URI”>
<!ELEMENT element.name EMPTY>
	<!ATTLIST element.name attribute.name ENTITY 
			#REQUIRED|#IMPLIED>
. . . (omitted)

<element.name attribute.name=”entity.name”>

Both of these techniques work great provided the content of the external entity will not cause a problem for the XML processor.  But what if we are dealing with a binary entity like an image or other format that does adhere to the standards of XML and/or the content model defined in the DTD?   In other words, what if we don’t want the entity parsed?  This is where things get a little more complicated.  

The first point that needs to be made is that binary entities can not be parsed.  If we declare them using a standard entity declaration, an error is going to occur.  View the following markup:

<!—This will cause a parser error -->
<!ENTITY img.stopsign SYSTEM “stop.gif”> 

The XML processor will attempt to process the contents of the external entity, which is not in acceptable XML format.  To work with external binary entities in XML, we need to do a couple of things for the declaration to work.

Notations

The first thing we need to do is declare a notation for the external binary entity.  Notations identify by name the format of an unparsed entity.  This declaration must be done in the DTD using the <!NOTATION> tag.  It looks very similar to the <!ENTITY> tag when making reference to an external entity.  The syntax is:

<!NOTATION notation.name SYSTEM|PUBLIC 
	“helper.application”>

Following the notation declaration, the binary (or unparsed) entity needs to be declared using the <!ENTITY> tag.

<!ENTITY entity.name SYSTEM “URI” NDATA notation.name>

Now that the binary entity is declared, we can reference it in our XML content.  But there is a catch.  Binary entities can only be referenced with in the value of an attribute that has been declared to be of type ENTITY or ENTITIES in the DTD.

Notice the use of the NDATA keyword.  This is the first time that you have seen it.    NDATA is short for “notation data” and refers to a specific <!NOTATION> declaration.  You will see this when we get to our example document.

Finally, let’s talk about the helper application that must be specified in the <!NOTATION> tag.  Selecting a this application is always a tough call since you cannot be guaranteed that it exists on the local machine.  What is more, XML is platform independent.  This is not a claim that to many helper applications can make.  Thus, this parameter is often left blank (“”).